initiateGiftCardPayment

HTTP method: POST

Use the initiateGiftCardPayment method to create a payment request with a gift card that covers either the full amount, or a part of the full amount.

For details of the payment flow, see Create a payment request using a gift card.
Test URL https://testgateway.altapaysecure.com/processor/API/<method>
Production URL https://<YourShopName>.altapaysecure.com/processor/API/<method>
Parameter Description Type Mandatory
payment_request_id

The id of the payment request to pay for in full or partly using a gift card.

string Yes
giftcard[account_identifier]

The card number of the gift card.

 string Yes
giftcard[account_authenticator]

The giftcard[account_authenticator] is the PIN code or password for the gift card.

This is not required when the giftcard[provider] parameter is set to test.

 string Yes
giftcard[provider]

The gift card provider that this gift card is for.

The supported values are:

  • test,
  • PPS, or
  • SVS.
 string Yes
giftcard[token]

If you have a gift card token from a previous payment, it can be used instead of the account identifier and provider parameters.

You can only use a token if the terminal has the specific gift card provider enabled.

string Yes

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Parameter Description Type
Result
  • Success if the gift card covered the full amount
  • Fail if the payment request fails
  • PartialSuccess if the gift card contains insufficient funds for the entire request
 string

XML result (success)

                    <?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/verify3dSecure</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
		<Transactions>
			<Transaction>
				<TransactionId>1</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<CardStatus>Valid</CardStatus>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<GiftCardToken>b3f16c8a7bb7e852656d4bb293f534a2f5d66d6a</GiftCardToken>
				<MaskedGiftCard>****5678</MaskedGiftCard>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e
				</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>captured</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>2.34</ReservedAmount>
				<CapturedAmount>0.00</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 12:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 12:34:56</UpdatedDate>
				<PaymentNature>GiftCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

XML result (partial success)

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/verify3dSecure</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>PartialSuccess</Result>
		<Transactions>
			<Transaction>
				<TransactionId>1</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<CardStatus>Valid</CardStatus>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<GiftCardToken>b3f16c8a7bb7e852656d4bb293f534a2f5d66d6a</GiftCardToken>
				<MaskedGiftCard>****5678</MaskedGiftCard>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e
				</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>captured</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>2.34</ReservedAmount>
				<CapturedAmount>0.00</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 12:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 12:34:56</UpdatedDate>
				<PaymentNature>GiftCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>